home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 December / macformat-031.iso / mac / Internet / HTML Software / BBEdit HTML Tools v1.3.1 / Documentation / templates.txt < prev    next >
Encoding:
Text File  |  1995-01-17  |  4.8 KB  |  113 lines  |  [TEXT/R*ch]
  1. Template Files
  2.  
  3. Overview
  4.     This is just a brief introduction into using template files. It will
  5.     tell you how to create a template file, discuss the special placeholders
  6.     that you can use, and finish off looking at include files.
  7.  
  8.  
  9. Introduction
  10.     To help you create your HTML documents, you can design a basic skeleton
  11.     HTML doucment that you can base your other documents on.
  12.     
  13.     The first thing that you may wish to do is to create a folder in
  14.     which to store your template files. I would suggest that you create this
  15.     in your BBEdit folder (but anywhere will do). Enclosed with this archive
  16.     is a folder called 'Templates'. You can either just drag this straight
  17.     to where you want your templates to live, or copy the files enclosed
  18.     into a folder you have created.
  19.     
  20.     Now that we have a folder to hold our templates, we need to set the
  21.     template file in the Preferences. Do this by opening the 'Utilities'
  22.     tool, and clicking on the 'Preferences' button. Select 'Template' from
  23.     the popup menu, and then click on the button. This will then ask you to
  24.     locate the template file - so do just that.
  25.     
  26.     If you have a number of different templates for different jobs, just
  27.     repeat this process when you want to change them.
  28.     
  29. Using a Template
  30.     Now that you have set the template file, to create a document using that
  31.     template, select the 'Document' tool. You will then have a window with a
  32.     number of fields that you may or may not wish to fill in. You really
  33.     must fill in the TITLE field, and I would strongly recommend that you
  34.     fill in the BASE field as well. You now have the choice of either just
  35.     creating a bare-bones document by clicking on 'OK', or using the
  36.     template, by clicking on 'Insert Template'. If you wish to make 'Insert
  37.     Template' the default button, you can option-click on it. (You can make
  38.     'OK' the default again by option-clicking on it too.). If you have used
  39.     the default template that came with this archive, then you should see
  40.     some of the information that you filled into the fields appear in the
  41.     newly created document, based on the template file. This is done with
  42.     'placeholders'.
  43.     
  44. Placeholders
  45.     You can include certain placeholders in your template file. These are
  46.     strings that will be replaced by some appropriate text. For example, you
  47.     may wish to add the current date, or user-name to the file, and this can
  48.     easily be done using placeholders.
  49.     
  50.     Placeholder            Action
  51.     ===========            ======
  52.     #TITLE#             the title of the document, as entered using the
  53.                         Document tool.
  54.     #LINK#                The link as entered using the Document tool.
  55.     #BASE#                The base as entered using the Document tool.
  56.     #NEXTID#            The Next ID of the document.
  57.     
  58.     #THEUSERNAME#        The user name (from chooser/sharing)
  59.     #THEMACHINE#        The machine name.
  60.     #THEDATE#            The short date (eg xx/xx/xx)
  61.     #THELONGDATE#        The long date (eg xx August 1994)
  62.     #THETIME#            The time
  63.     #THEROOT#            The root directory on the machine
  64.     #THESERVER#            The URL of your server.
  65.     #THEPREFIX#            The prefix to access your documents from the server.
  66.  
  67. Include Files
  68.     Those of you who have used C and other programming languages will be
  69.     familiar with include files. These are other files that can be included
  70.     in the current file by using a reference to it (eg #include "test.html")
  71.     Your HTML documents can therefore include other files, such as a header
  72.     or footer file.
  73.     
  74.     The way the standard include file reference is processed is that the
  75.     file will replace the reference to it. So if your template contains a
  76.     reference to a footer, then you write
  77.     
  78.             #include "footer.html"
  79.     
  80.     When this template is used, this reference will be overwritten by the
  81.     contents of the file.
  82.     
  83.     Now there will be some of you who will be disappointed by this. Surely
  84.     if the #include statement is overwritten, then it won't be possible to
  85.     update the document if you ever decide you want to change the contents
  86.     of the footer.
  87.     
  88.     So what you really want is a way of ensuring that there is a reference
  89.     to a file that stays in your document permanently. This raises the
  90.     problem of how to have these file references in the document without
  91.     fouling up the HTML for the user. My solution is to embed the include
  92.     statement in an HTML comment. This way the user never sees it, but the
  93.     reference remains in the document. The syntax is...
  94.     
  95.             <!-- #include "footer.html" -->
  96.     
  97.             <!-- end include -->
  98.     
  99.     Note that there is a closing comment. This is necessary because when the
  100.     document is updated it needs to know which area of text can be replaced
  101.     by the footer file. (In the event of the file not being found, a message
  102.     to that effect will be inserted).
  103.     
  104. Location
  105.     Now, these include files should be stored in the same folder as your
  106.     template file, so that the tools can find them easily. You can create
  107.     subfolders in the template folder if you wish, as long as you change the
  108.     file reference accordingly, eg 
  109.     
  110.             #include ":Footers:myFooter.html"
  111.             
  112.     (take note of the colons).
  113.